home *** CD-ROM | disk | FTP | other *** search
/ Scene Storm / Scene Storm - Volume 1.iso / coding / c / ctimer / ctimer.doc next >
Text File  |  1995-11-05  |  4KB  |  110 lines
  1.  
  2.  
  3.  
  4.                             C T i m e r  
  5.  
  6.   Introduction 
  7.  
  8.      Two distinct timers are included in this package:
  9.  
  10.        CTimer1  for system 1.3 or 2
  11.        CTimer2  for system 2 only.
  12.  
  13.      Either can be used to measure the execution of any section of code from a
  14.   single line to a complete programme.
  15.   
  16.      The main use of CTimer will be to help fine-tune any program which you
  17.   would like to speed up, by showing where excess time is being used, or 
  18.   showing  where a little machine_coding could be most profitable. 
  19.    
  20.      CTimer itself is a module that when linked to a suitably annotated
  21.   programme  measures the execution time of selected sections of the programme.
  22.   The two versions are used in the same way.
  23.  
  24.  
  25.   CTimer test.
  26.  
  27.      Each drawer has the files:
  28.      
  29.       ctimer[x].o  object file to be linked with the programme under test.
  30.       ctimer[x].s  source for ctimer[x].o 
  31.       test.c       test file ready to be compiled & linked with ctimer.o.
  32.       test.o       compiled version of test.c (Lattice)
  33.       test[x]      executable test file.
  34.       test[x]_linker  Blink command line.
  35.  
  36.      To reproduce test[x], execute test[x]_linker (may need modification to
  37.   suit your setup).  Note that CTimer1 uses the mathffp.library. 
  38.  
  39.      Function1 measures the dead time, which must be deducted from the reported
  40.   running time to get a true figure.
  41.  
  42.      Function2 measures the time taken by a Ctime/Cend pair - which will add to
  43.   the total running time of the program.
  44.  
  45.      Function3 shows one way of handling multiple exits - the report will not
  46.   differentiate between exit points.
  47.  
  48.   Use
  49.  
  50.      CTimer has three accessable functions, Ctime, Cend, and Creport
  52.     Ctime(reference number) is called at the start of the section of code to
  53.     be timed, a different reference for each section.
  54.      
  55.     Cend(reference number) is called at the end of the timed section.
  56.     Reference must match the starting reference.
  57.  
  58.     Creport() is called at the exit from the programme.
  59.     If there are a number of possible exits it must be called at each.
  60.  
  61.     A section may be a complete module, a function, or even a single line;
  62.     the only restriction is that it must have one unique entry point for Ctime.
  63.  
  64.     Sections may be nested, see example in test.c.
  65.  
  66.     When the required sections have been annotated, compile and link with
  67.     ctimer[x].o.
  68.  
  69. Operation
  70.  
  71.     Operation of the programme is simple.  When a Ctime call is noted its
  72.     reference is recorded with the current system time.  On receipt of a
  73.     Cend the current list of Ctime calls is scanned for a matching
  74.     reference, a new current time noted and the time difference stored.
  75.   
  76. Output
  77.  
  78.     Output is to stdout (the programme under test must provide a stdout - the
  79.     test.c files show a simple way of providing one for WorkBench programs)
  80.     in the form
  81.  
  82.         function1   visits 6   secs 1  msecs  44   micros 186
  83.         function2   visits 2   secs 0  msecs   0   micros 250
  84.         etc 
  85.      
  86.     visits - the number of times that section of code was used.
  87.     
  88.     time   -  running total of the time spent within the section.  For
  89.   function2 above the average time per visit would have been 125 micros.  If
  90.   the current figure for dead time were 40 micros, actual running time would
  91.   be 85 micros.    
  92.  
  93.  
  94.  
  95.                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  96.  
  97.    CTimer is Freeware.  It may be copied and distributed freely and used
  98.  without charge for non_profit-making purposes.  Authority for profit-making  
  99.  use should be obtained from the author below.
  100.  
  101.    No responsibility can be accepted for any loss resuling from its use.
  102.  
  103.    Comments, suggestions, bug-reports all welcome.
  104.  
  105.    Chas A. Wyndham,
  106.    1265 Canning Mills Road,
  107.    Roleystone,
  108.    WA 6111.
  109.    Australia 
  110.